Skip to content

Foundry data-plane: add draft flag to Agent versions#43979

Merged
akaila merged 1 commit into
Azure:feature/foundry-releasefrom
akaila:ashishkaila/agents/draft-property
Jun 26, 2026
Merged

Foundry data-plane: add draft flag to Agent versions#43979
akaila merged 1 commit into
Azure:feature/foundry-releasefrom
akaila:ashishkaila/agents/draft-property

Conversation

@akaila

@akaila akaila commented Jun 15, 2026

Copy link
Copy Markdown

Summary

Adds an optional draft: boolean (default false) to the Foundry Agent
data-plane models so callers can mark a version as a draft/candidate
distinct from the version identifier itself.

Models updated (specification/ai-foundry/data-plane/Foundry/src/agents/models.tsp)

  • CreateAgentVersionRequest — added draft?: boolean = false.
    Propagates automatically to CreateAgentRequest and UpdateAgentRequest
    via ...CreateAgentVersionRequest spread.
  • AgentVersionObject (response) — added draft?: boolean = false.

Semantics

  • Field is optional on both request and response; absent is equivalent to
    false.
  • Set at version-creation time and immutable on a given version (each
    PATCH creates a new version, so customers re-state draft per call).
  • Server semantics (separate service PRs): draft versions are recorded
    but excluded from default latest resolution and are not
    auto-promoted.

Why a flag, not an identifier convention

This metadata flag is intentionally decoupled from the version-identifier
scheme (e.g. integer vs major.minor vs draft-{timestamp}). Callers
need a stable, explicit way to express "this is a candidate" without
overloading the identifier.

Compatibility

Fully additive:

  • No required[] changes.
  • No removals, renames, or type changes.
  • Both v1 and virtual-public-preview swaggers updated by the
    emitter; diff is pure additions.

Validation

  • npx tsp compile . (from data-plane/Foundry) — compiles cleanly,
    no warnings.
  • npx tsp format on the edited file — no formatting changes.
  • Regenerated swaggers committed alongside the spec edit.

Related

  • Tracking design doc and downstream service implementation in the Vienna
    repo (internal): PR 2147685 (design), PR 2151464 (data-plane plumbing).

@github-actions

github-actions Bot commented Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown

Next Steps to Merge

Important checks have failed. As of today they are not blocking this PR, but in near future they may.
Addressing the following failures is highly recommended:
  • ⚠️ The check named Swagger BreakingChange has failed. To unblock this PR, follow the process at aka.ms/brch.
If you still want to proceed merging this PR without addressing the above failures, refer to step 4 in the PR workflow diagram.

Comment generated by summarize-checks workflow run.

@github-actions github-actions Bot added data-plane TypeSpec Authored with TypeSpec labels Jun 15, 2026
@github-actions

github-actions Bot commented Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language API Review for Package
TypeSpec Azure.AI.Projects

Comment generated by After APIView workflow run.

@akaila

akaila commented Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

CI failures - analysis (not blocking)

The red checks here are pre-existing tooling false positives for the ai-foundry/Foundry tree, not real issues with this PR.

Swagger BreakingChange - tooling crash, not a real BC

From the check log:

"oadViolationsCnt": 0, "errorCnt": 1
FATAL: Error: File '...openapi3/v1/microsoft-foundry-openapi3.json' is not a valid OpenAPI 2.0 definition (expected 'swagger: 2.0')

The OAD (OpenAPI Diff) tool only understands Swagger 2.0. This folder emits OpenAPI 3.0 (per tspconfig.yaml: emit: ["@typespec/openapi3"]). The tool crashes on parse - zero real breaking-change violations were detected. Breaking Change (Cross-Version) (which uses an OpenAPI-3-compatible analyzer) is green.

TypeSpec Validation - pre-existing folder-structure complaints

Errors are about service folders (sdk-agents, sdk-extensions-openai, sdk-projects-agents, sdk-service-agents-contracts) not matching the PascalCase regex /^[A-Za-z0-9]+$/, plus cross-folder imports. None introduced by this PR.

Swagger LintDiff - same OAD/OpenAPI-3 mismatch as above

SDK Validation - Java - pre-existing

The exact same Java SDK Validation failure appears on the most recently merged Foundry PR #43821 (merged 2026-06-08) and #43981 (merged 2026-06-16). This is a pre-existing issue with the Java emitter for this tree.

SDK Validation - .NET - intermittent/flaky

.NET SDK Validation is flaky for this tree:

  • #43821 (merged 2026-06-08): .NET ✅
  • #43981 (merged 2026-06-16): .NET ❌ (still merged)
  • #43620 (merged 2026-06-19): .NET ✅

Repo-wide pattern - precedent

The most recently merged Foundry PRs (#43821, #43981, #43620) show the same pattern of failures and were merged successfully.

What this PR actually changes (all backwards-compatible)

Schema Change Compatibility
CreateAgentVersionRequest + optional draft?: boolean = false additive
CreateAgentRequest + optional draft (via spread) additive
UpdateAgentRequest draft deliberately omitted via OmitProperties — updates always produce non-draft versions no change
AgentVersionObject + optional draft?: boolean = false additive
  • No required[] changes
  • No removals, renames, or type changes
  • Optional on both request and response

@akaila akaila requested review from Copilot and victordibia June 15, 2026 20:41
Copilot AI reviewed Jun 15, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR adds a new optional draft: boolean flag (default false) to Foundry Agents’ version models to distinguish draft/candidate versions from released versions, and regenerates the OpenAPI outputs for v1 and virtual-public-preview.

Changes:

  • Added draft?: boolean = false to CreateAgentVersionRequest (request) and AgentVersionObject (response) in TypeSpec.
  • Updated UpdateAgentRequest to omit the draft field via OmitProperties<..., "draft">.
  • Regenerated OpenAPI 3 documents (v1 and virtual-public-preview) to include the new draft property in the affected schemas.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File Description
specification/ai-foundry/data-plane/Foundry/src/agents/models.tsp Introduces the draft flag on agent version request/response models; changes update request composition.
specification/ai-foundry/data-plane/Foundry/openapi3/virtual-public-preview/microsoft-foundry-openapi3.json Emitter output reflecting the new draft property in preview OpenAPI schemas.
specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.json Emitter output reflecting the new draft property in v1 OpenAPI schemas.

Comment thread specification/ai-foundry/data-plane/Foundry/src/agents/models.tsp
@akaila akaila added the PublishToCustomers Acknowledgement the changes will be published to Azure customers. label Jun 22, 2026
@akaila akaila force-pushed the ashishkaila/agents/draft-property branch from 636130f to 0fb76f9 Compare June 25, 2026 14:19
@akaila akaila force-pushed the ashishkaila/agents/draft-property branch from 7c4d7b7 to 9929c46 Compare June 25, 2026 14:41
ravimeda
ravimeda reviewed Jun 25, 2026
View reviewed changes

@ravimeda ravimeda left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ARM API Review

Posting findings from the ARM API Reviewer agent (critic-verified, 1 iteration, converged) against commit 99b9034. See inline comments for findings 1-2.

Comment thread specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.json Outdated
Comment thread specification/ai-foundry/data-plane/Foundry/src/agents/models.tsp Outdated
Copilot AI reviewed Jun 25, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

Comment thread specification/ai-foundry/data-plane/Foundry/src/agents/routes.tsp Outdated
Comment thread specification/ai-foundry/data-plane/Foundry/src/agents/models.tsp Outdated
Comment thread specification/ai-foundry/data-plane/Foundry/src/agents/models.tsp
Comment thread specification/ai-foundry/data-plane/Foundry/src/agents/models.tsp
@akaila

akaila commented Jun 26, 2026

Copy link
Copy Markdown
Author

@ravimeda can you please do another review. Thanks

dargilco
dargilco reviewed Jun 26, 2026
View reviewed changes
Comment thread specification/ai-foundry/data-plane/Foundry/src/agents/routes.tsp Outdated
dargilco
dargilco reviewed Jun 26, 2026
View reviewed changes
Comment thread specification/ai-foundry/data-plane/Foundry/src/agents/models.tsp Outdated
@akaila
Foundry data-plane: add draft flag to Agent versions
e8bf0c2 
Adds an optional `draft: boolean` (default false) to:
- CreateAgentVersionRequest
- CreateAgentRequest (via spread)
- AgentVersionObject (response)

Excluded from UpdateAgentRequest via OmitProperties — draft is immutable
once set at version-creation time.

Also adds `include_drafts` query parameter to listAgentVersions.
Draft versions are excluded from listings by default.

Fully additive — no required[] changes, no removals.
@akaila akaila mentioned this pull request Jun 26, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments
@ravimeda ravimeda ravimeda approved these changes
@johanste johanste Awaiting requested review from johanste
@trrwilson trrwilson Awaiting requested review from trrwilson trrwilson is a code owner
@glecaros glecaros Awaiting requested review from glecaros glecaros is a code owner
@dargilco dargilco Awaiting requested review from dargilco dargilco is a code owner

Assignees

No one assigned

Labels

Authorization Cognitive Services Compute Container Service data-plane PublishToCustomers Acknowledgement the changes will be published to Azure customers. TypeSpec Authored with TypeSpec

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@akaila @ravimeda @dargilco